DevelopersIO 2023 大阪 – 勉強会「S3 + MkDocs でナレッジサイトをお手軽に構築・運用する話」 #devio2023

本ブログは 2023/07/19の DevelopersIO 2023 大阪 にて開催される プチ勉強会(at AWS質問ブース)用の資料となります。

「 S3 + MkDocs でナレッジサイトをお手軽に構築・運用する話 」というタイトルで 勉強会をします！ (しました！)

この勉強会の目的

• ナレッジサイト(CCG)のアーキテクチャを紹介する
• アーキテクチャ選定までの話をする
• ナレッジ運用周りの話をする

Classmethod Cloud Guidebook(CCG)について

Classmethod Cloud Guidebook は CMメンバーズ(請求代行サービス)向けに 公開している ナレッジサイト です。

お客様のクラウド推進を支援すべく、 AWSのセキュリティや統制、ガイドライン周りで 役立つナレッジを公開しています。

詳しくは以下紹介ブログやデモサイトを参照ください。

• クラスメソッドメンバーズのお客様向けに公開している「Classmethod Cloud Guidebook (CCG)」の使い方 | DevelopersIO
• Classmethod Cloud Guidebook デモサイト

CCGのアーキテクチャ

AWS周り

シンプルに書いてしまうと以下のようなアーキテクチャとなります。

S3バケットに静的サイトジェネレーターのビルド(site)を投入します。 ユーザーは CloudFront 経由で site にアクセスします。

ただし、本サイトは Classmethod Members 限定で公開しているため、 ここに認証などの仕組みが加わります。

そこにセキュリティ周り、もろもろ考慮した結果、 最終的には以下のような構成となっています。 (詳細は画像先の Speaker Deck を参照してください)

– 画像: CDKを使って爆速でナレッジサイトを公開した話 - Speaker Deck

MkDocs周り + デモ

静的サイトジェネレーターとして MkDocs を使っています。 MkDocs のコンテンツをS3に上げる流れは以下のとおりです。

見たほうが分かりやすいと思うので、 簡単なデモを行います。

MkDocs サイト構築に必要なのは サイト構成ファイル( mkdocs.yml ) と 実際のページ ( 各Markdownファイル ) です。

以下のような mkdocs.yml を用意します。

site_name: MkLorum
site_url: https://example.com/
nav:
    - Home: index.md
    - About: about.md
theme: readthedocs

そして実際のページとして 2つほど用意します。

$ cat ./docs/index.md
# MkDocsデモ
xxx

$ cat ./docs/about.md
# このサイトについて
xxx

mkdocs serve コマンドでローカルでサイト表示を確かめられます。

mkdocs build コマンドでサイトに必要なコンポーネントを出力できます。 デフォルトでは site ディレクトリに作成されます。

$ mkdocs build
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory:
            /Users/kawahara.masahiro/Documents/devio-osaka-2023/mkdocs-demo/site
INFO     -  Documentation built in 0.03 seconds

$ ls site/
404.html       css            img            js             sitemap.xml
about          fonts          index.html     search         sitemap.xml.gz

これを S3(静的ウェブサイトホスティング有効化) へ展開します。

$ aws s3 sync ./site s3://${S3BucketName}/site

ウェブサイト ( ${バケット名}.s3-website-ap-northeast-1.amazonaws.com/site ) へアクセスできることを確認できました！

これまでの流れを、GitHub Actions を使って効率化しています。

• 参考: MkDocsサイトを S3へデプロイする GitHub Actions ワークフローを作ってみる | DevelopersIO

ツール選定のお話

CCG作成の背景を紹介します。

もともと既存の似たようなプロダクト、サービスがありましたが、 それは Google Docs で管理されていました (70ページ超！)。

さらにメンテナンス不足でナレッジが陳腐化する課題もありました。

そういった背景があり、以下の要件を満たすべくツール選定から始めました。

• テキスト管理であること
• バージョン管理ができること
• 文章レビューのプロセスを作れること
• 楽にナレッジを提供できること

テキスト管理であること

Markdown ファイルを作成、管理していく方針としました。

• プレーンテキストのデファクトスタンダード
• 社内メンバーがブログ執筆などで慣れ親しんでいる
• コンテンツの内容ごとにファイルを分割して、メンテしやすく

ほか候補 … Word/Google Docs, PowerPoint/Google Slides

バージョン管理ができること

Git でバージョン管理を行う方針としました。

• テキストがいつ・どう更新されたか、把握できるように
• コンテンツ改善の遷移を把握できるように

ほか候補 … Google Docs のバージョン管理機能

文章レビューのプロセスを作れること

GitHub で実現しています。

• mainブランチは直接更新できないように設定
• 更新の際にはプルリクエストを作成する
• レビュアーによる承認が一定数に達しないと、マージできないように設定

ほか候補 … Google Docs のコメント機能、提案モード

楽にナレッジを提供できること

作り込みはしたくないので、 静的サイトジェネレーター を各種調べました。

社内のナレッジとして MkDocs と Sphinx が 比較的多かったので、両者で検討していました。

• MkDocs の記事一覧 | DevelopersIO
• Sphinx の記事一覧 | DevelopersIO

最終的には MkDocs の以下メリットが大きかったので、 MkDocs採用に至りました。

• シンプルさ、始めやすさ
• MkDocs for Material (拡張プラグイン) の良さ

Sphinx も良く、「よりカスタマイズできる」印象はありました。 ただ、ドキュメントの書き方のデフォルトが Markdown ではなく reStructuredText だったのが、ちょっと辛みに感じました。

運用のお話

textlint による文章校正

– GitHub - textlint/textlint: The pluggable natural language linter for text and markdown.

ドキュメントの品質を一定以上に保つために、 textlint による自動校正を取り入れています。

▼ 校正イメージ

• 【GitHub Actions】Markdown 執筆に textlintの自動校正を取り入れる | DevelopersIO

ナレッジの活発な更新に向けて

▼ レビュープロセスのフロー化

改善のサイクルを回していく仕組みを作成・周知しています。

▼ 社内からの Contrubute(貢献)を募集

貢献ガイド(CONTRIBUTING.md) を作成して、社内周知しています。 気軽にIssue, Pull Requestを投げられる環境作りを意識しています。

今後について

以下継続的な改善を進めていきたいです。

• UI/UXの改善: ユーザーが情報を探しやすく、アクセスしやすく
• コンテンツ改善・追加の継続: AWSのアップデートやベストプラクティスをキャッチアップ、都度更新できる体制・仕組み作り
• ナレッジの陳腐化対策: 更新されないコンテンツの棚卸しの体制・仕組み作り
• フィードバック ⇔ 改善 サイクルを加速させる: 社内メンバー全員でコンテンツを更新できる文化醸成

おわりに

以上、Classmethod Cloud Guidebook のアーキテクチャやツール選定、運用のお話でした。

今後もどんどんアップデートして、改善を進めていきたいと思っております。